<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 
<html>
<head>
<title>Introduction to PyCairo</title>
<link rel="stylesheet" href="/cfg/format.css" type="text/css">
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<meta name="keywords" content="PyCairo, Python, Cairo, introduction">
<meta name="description" content="This is an introductory chapter of the
PyCairo tutorial.">
<meta name="language" content="en">
<meta name="author" content="Jan Bodnar">
<meta name="distribution" content="global">

<script type="text/javascript" src="/lib/jquery.js"></script>
<script type="text/javascript" src="/lib/common.js"></script>

</head>

<body>

<div class="container2">

<div id="wide_ad" class="ltow">
<script type="text/javascript"><!--
google_ad_client = "pub-9706709751191532";
/* 160x600, August 2011 */
google_ad_slot = "2484182563";
google_ad_width = 160;
google_ad_height = 600;
//-->
</script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
</div>

<div class="content2">


<a href="/" title="Home">Home</a>&nbsp;
<a href="..">Contents</a>


<h1>Introduction to PyCairo</h1>


<p>
This is PyCairo tutorial. This tutorial will teach you the
basics and some advanced topics of the Cairo 2D library with
the Python language. In most examples, we will use the Python GTK
backend to produce our output. Images used in this tutorial can
be downloaded <a href="/img/gfx/pycairo/images.zip">here</a>.
</p>

<div class="big_hor">
<script type="text/javascript"><!--
google_ad_client = "ca-pub-9706709751191532";
/* big_horizontal */
google_ad_slot = "2904953388";
google_ad_width = 728;
google_ad_height = 90;
//-->
</script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
</div>


<h2>Computer graphics</h2>

<p>
There are two different computer graphics. <b>Vector</b> and <b>raster</b> graphics. 
Raster graphics represents images as a collection of pixels. Vector graphics 
is the use of geometrical primitives such as points, lines, curves or polygons 
to represent images. These primitives are created using mathematical equations. 
</p>

<p>
Both types of computer graphics have advantages and disadvantages. The advantages 
of vector graphics over raster are:
</p>

<ul>
<li>smaller size</li>
<li>ability to zoom indefinitely</li>
<li>moving, scaling, filling or rotating does not degrade the quality of an image </li>
</ul>


<h2>Cairo</h2>

<p>
Cairo is a library for creating 2D vector graphics. It is written in the C 
programming language. Bindings for other computer languages exist. Python, Perl, 
C++, C#, Java. Cairo is a multiplatform library, works on Linux, BSDs and OSX.
</p>

<p>
Cairo supports various backends. Backends are output devices for displaying
the created graphics.
</p>

<ul>
<li>X Window System</li>
<li>Win32 GDI</li>
<li>Mac OS X Quartz</li>
<li>PNG</li>
<li>PDF</li>
<li>PostScript</li>
<li>SVG</li>
</ul>

<p>
This means, we can use the library to draw on windows on Linux/BSDs, 
Windows, OSX and we can use the library to create
PNG images, PDF files, PostScript files and SVG files.
</p>

<p>
We can compare the cairo library to the <b>GDI+</b> library on Windows 
OS and the <b>Quartz 2D</b> on Mac OS. Cairo is an open source software 
library. From version 2.8, Cairo is part of the <b>GTK</b> system.
</p>


<h2>Definitions</h2>


<p>
Here we will provide some useful definitions. To do some drawing in PyCairo, we 
must first create a <b>drawing context</b>. The drawing context holds all of the 
graphics state parameters that describe how drawing is to be done. This includes 
information such as line width, colour, the surface to draw to and many other things. 
It allows the actual drawing functions to take fewer arguments to simplify the interface.
</p>

<p>
A <b>path</b> is a collection of points used to create primitive shapes such as lines, arcs
and curves. There are two kinds of paths. Open and closed paths. In a closed path, 
starting and ending points meet. In an open path, starting and ending point do not meet. 
In PyCairo, we start with an empty path. First we define a path and then we make them 
visible by stroking and/or filling them. After each <code>stroke()</code> or <code>fill()</code> 
method calls, the path is emptied. We have to define a new path. If we want to
keep the existing path for later drawing, we can use the <code>stroke_preserve()</code>
and <code>fill_preserve()</code> methods. 
A path is made of subpaths.
</p>

<p>
A <b>source</b> is the paint we use in drawing. We can compare the source to a pen or ink, 
that we use to draw the outlines and fill the shapes. There are four kinds of basic sources. 
Colours, gradients, patterns and images.
</p>


<p>
A <b>surface</b> is a destination that we are drawing to. We can render documents using the PDF 
or PostScript surfaces, directly draw to a platform via the Xlib and Win32 surfaces.
</p>

<p>
Before the source is applied to the surface, it is filtered first. The <b>mask</b> is used as a filter. 
It determines where the sourse is applied and where not. Opaque parts of the mask allow 
to copy the source. Transparent parts do not let to copy the source to the surface.
</p>

<p>
A <b>pattern</b> represents a source when drawing onto a surface. In PyCairo, a pattern is something 
that you can read from, that is used as the source or mask of a drawing operation. Patterns can be solid, 
surface-based or  gradients.
</p>

<h2>Sources</h2>

<p>
To create this tutorial, we have used the following materials. The 
<a href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/CocoaDrawingGuide/Introduction/Introduction.html">Apple Cocoa drawing guide</a>, 
the <a href="http://cairographics.org/documentation/pycairo/2/index.html">PyCairo reference</a> and the
<a href="http://cairographics.org/documentation/">Cairo documentation</a>.
</p>

<div class="botNav, center">
<span class="botNavItem"><a href="/">Home</a></span> ‡ <span class="botNavItem"><a href="..">Contents</a></span> ‡ 
<span class="botNavItem"><a href="#">Top of Page</a></span>
</div>


<div class="footer">
<div class="signature">
<a href="/">ZetCode</a> last modified September 1, 2012  <span class="copyright">&copy; 2007 - 2013 Jan Bodnar</span>
</div>
</div>

</div> <!-- content -->

</div> <!-- container -->

</body> 
</html>



